home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus Special 20 / AMIGAplus Sonderheft 20 (1999)(ICP)(DE)[!].iso / PublicDomain / Alternatives / LinuxAPUS / Docs / clgen.txt next >
Text File  |  1999-01-01  |  33KB  |  773 lines
  1.  
  2.                           clgen v1.3 (12-Jan-98)
  3.                   A generic driver for Cirrus Logic based
  4.                graphic boards for the Amiga under Linux/m68k
  5.  
  6.                   Copyright (c) 1997,1998 by Frank Neumann
  7.  
  8. ------------------------------------------------------------------------
  9.  
  10. This document describes installation and usage of the framebuffer device
  11. driver for Cirrus Logic based graphic boards for the Amiga under Linux/m68k.
  12.  
  13. IT IS IMPORTANT THAT YOU READ ALL OF THIS BEFORE EVEN ATTEMPTING TO USE
  14. THE DRIVER! DON'T EXPECT X11 TO WORK AS ON INTEL LINUX BOXES!
  15.  
  16. 0) Changes since v1.2
  17.    - some bugfixes
  18.    - now accepts monitorcap: and mode: on command line
  19.  
  20.    Changes since v1.0
  21.    - text consoles on your graphic board! Just start the kernel with
  22.      amiboot [..] video=clgen
  23.    - For 8 bpp (standard case), console scrolling&filling is accelerated
  24.    - Picasso IV support
  25.    - no more need to use the "tog" tool
  26.    - correct standard VGA color palette
  27.    - uses the FB_ACTIVATE_* flags correctly now
  28.    - correct behaviour when used with fbset
  29.  
  30.    Important! The driver now sits in fb0*, so you can remove the old fb1*
  31.    entries from /dev. Though, you'll either have to rename your fb0*
  32.    entries to more meaningful names ("fb0pal" is a bit irritating for
  33.    1024x768 :-), or create additional symlinks with meaningful names;
  34.    see below in "Creating /dev entries".
  35.  
  36.  
  37. 1) Supported hardware
  38. ---------------------
  39.  
  40. This driver supports the following graphic boards:
  41. - Piccolo SD64 (Ingenieurbuero Helfrich)
  42. - Piccolo      (Ingenieurbuero Helfrich)
  43. - EGS Spectrum (GVP)
  44. - Picasso II   (Villagetronic)
  45. - Picasso IV   (Villagetronic)
  46.  
  47. The Picasso II is only supported in linear (non-segmented) mode. Please
  48. make sure that the switch on the rear of the board is set to linear mode.
  49.  
  50. All other boards only do linear mode, and should thus work out of the box.
  51. It shouldn't matter whether you use them in Z2 or Z3 mode; the only
  52. difference probably being that throughput into the Z2 area is not as fast as
  53. into Z3 memory.
  54.  
  55.  
  56. 2) Features
  57. -----------
  58.  
  59. - Variable resolutions: The user can create his own resolutions if he knows
  60.   what he is doing. The driver comes with some pre-generated resolutions, 
  61.   though:
  62.   640x480, 31.25 kHz, 60 Hz, 25 MHz PixClock (startup mode)
  63.   800x600, 48 kHz, 72 Hz, 50 MHz PixClock
  64.   1024x768, 55.8 kHz, 70 Hz, 80 MHz PixClock
  65.   320x200, 31.4 kHz, 70 Hz, 25 MHz PixClock (Super-LoRes ;-)
  66.   1024x768i (interlaced), 31.5 kHz, 77 Hz, 44.9 MHz PixClock
  67.   1024x768hi (interlaced), 46.5 kHz, 113 Hz, 66.2 MHz PixClock
  68.   1280x1024i (interlaced), 51 kHz, 87 Hz, 80 MHz PixClock
  69.  
  70.   Interlaced modes should not exceed 1024 lines; this is a "Todo" item.
  71.  
  72. - Color depth: Right now, only 1 bit (monochrome) and 8 bit PseudoColor
  73.   (256 colors, using a LookUp table) are supported. There is already
  74.   code for 16 bit HiColor and 24/32 bit TrueColor in the driver, but it is
  75.   still disabled because the XF68_FBDev Xserver doesn't yet support these 
  76.   modes correctly.
  77.  
  78. - Virtual screens: Supports "AutoScroll" resolutions larger than the visible
  79.   screen area, e.g. when used with the Xserver. For example, on a 4 MB
  80.   SD64 board using 8 bits per pixel, you can create a workspace as large
  81.   as 2048x2048 pixels. Moving the cursor towards one of the screen borders
  82.   will scroll the display in that direction.
  83.   Please note that in monochrome modes you can only use 1/4 of the display 
  84.   memory due to hardware limitations; for that reason, on a 4 MB board
  85.   the maximum virtual resolution in monochrome is also limited to
  86.   2048x2048 pixels.
  87.  
  88. - DoubleScan mode: For extra LowRes modes, the driver uses the "doublescan"
  89.   feature of the vga controller which outputs every scanline twice. The
  90.   supplied 320x200 mode uses this. Amaze your friends with a game like
  91.   Thrust filling the entire screen! :-)
  92.   Please note that this mode is not yet available with fbset, as it misses
  93.   a little option I have to add. It's still in the kernel, though.
  94.  
  95. - Supports multiple boards in one computer: While probably not many users
  96.   will ever need this feature, I found it very helpful while developing. :-)
  97.   At startup, the driver looks for all boards it supports, and initializes
  98.   and registers each of them.
  99.   TODO: This does currently NOT work (v1.2) due to the number of changes
  100.   I had to put in for console support.
  101.  
  102. - Should correctly determine the amount of DRAM available on the board
  103.   (please mail me if this does not work on your board!)
  104.  
  105. - Allows to set the maximum vertical/horizontal frequencies with regard to
  106.   the connected monitor. This is done either at the amiboot command line
  107.   (recommended) or via a little program "freq" (see below).
  108.  
  109. - Allows larger consoles than the default right at kernel startup time;
  110.   no PC-ish hassle with something like svgatextmode!
  111.  
  112. 3) Installing the driver
  113. ------------------------
  114. If you received this text file together with a precompiled kernel 
  115. containing the clgen driver, you are ready to go; you can then safely
  116. skip this section and go to the next, "Creating /dev entries".
  117.  
  118. Otherwise, you will have to compile a kernel of your own. This, of course,
  119. requires a working Linux system complete with gcc, binutils and everything
  120. else that is needed to compile&link a kernel.
  121.  
  122. You will now have to apply the clgen source patch to the kernel source tree.
  123. The file containing the patch is named "clgen_diffs" and should be in the
  124. archive you unpacked. However, it might also already have been applied
  125. to the kernel source tree; if that is so, I forgot to update this text
  126. file in time; in that case bug me to update it. :-)
  127. I used a 2.0.33 kernel source tree. Adapting the driver for 2.1.xx kernels
  128. will be the next thing to do. Please be patient.
  129.  
  130. Applying source patches should be something you know about; in a nutshell:
  131. (cd /usr/src/linux; patch -p0 -s < "path_to_clgen_diffs" )
  132.  
  133. After that, copy the driver main files (clgen.c and clgen.h) to their
  134. destination in "arch/m68k/amiga/" in the kernel source tree.
  135.  
  136. Next, start the configuration with 
  137. # make config
  138.  
  139. When asked for the CLGEN driver, answer with "y":
  140. [..]
  141. Amiga Cirrus Logic boards support (CONFIG_FB_CLGEN) [Y/n]: y
  142.  
  143. After this you can do the usual
  144. # make clean; make dep; make
  145.  
  146. and have one or maybe even LOTS of cups of coffee while you wait for the
  147. compiler to finish. You should end up with a "vmlinux" kernel binary in
  148. /usr/src/linux containing the clgen driver. Copy it to the usual location
  149. where you keep kernel images on the AmigaOS side.
  150.  
  151.  
  152. 4) Creating /dev entries
  153. ------------------------
  154.  
  155. To allow any application program to communicate with the (kernel-based) 
  156. driver (I write "any", although the mostly used application is going to
  157. be the Xserver of the X Window System), you now have to create some entries 
  158. in /dev. Usually, you already have a couple of fb0* nodes in there which 
  159. are associated with the built-in video hardware of the Amiga (OCS, ECS or 
  160. AGA).
  161.  
  162. Now, when starting the kernel with the console on the graphic board, the
  163. fb0 framebuffer device is not used by the Amiga's video chipset (OCS/ECS/AGA),
  164. but by the graphic board. This means you still use the fb0* entries in
  165. /dev, but the video modes "behind" the names have changed (they are now
  166. the predefined modes in the clgen driver). 
  167.  
  168. You could now either remove the old fb0* devices and create new ones with
  169. the same major/minor device number, but with more meaningful names, or
  170. (what I recommend) keep the old ones and create the new, meaningful names
  171. as symlinks pointing to the old ones.
  172.  
  173. Here is what I suggest; these are sort-of telling names that correspond to 
  174. the modes that come with the driver.
  175.  
  176. First, log in as root, go to /dev, check that there are already the
  177. "typical" fb0 devices for Amiga; the following should exist:
  178.  
  179. crw-rw-rw-   1 root     root      29,   0 Aug  5  1996 fb0current
  180. crw-rw-rw-   1 root     root      29,   1 Oct  1  1996 fb0autodetect
  181. crw-rw-rw-   1 root     root      29,   2 Oct 21 20:11 fb0ntsc
  182. crw-rw-rw-   1 root     root      29,   3 Oct 21 20:11 fb0ntsc-lace
  183. crw-rw-rw-   1 root     root      29,   4 Oct 21 17:34 fb0pal
  184. crw-rw-rw-   1 root     root      29,   5 Dec 31  1996 fb0pal-lace
  185. crw-rw-rw-   1 root     root      29,   6 Dec  5  1996 fb0multiscan
  186. crw-rw-rw-   1 root     root      29,   7 Dec  5  1996 fb0multiscan-lace
  187. crw-rw-rw-   1 root     root      29,   8 Oct 21 17:34 fb0a2024-10
  188.  
  189. If they don't exist, get the fbset program source, compile and install
  190. it; it contains a target in the Makefile to create those (and more) device
  191. nodes for you.
  192.  
  193. Now, create the clgen device nodes as symlinks pointing to the old devices:
  194. # ln -s fb0ntsc fb0cl-low
  195. # ln -s fb0ntsc-lace fb0cl-med
  196. # ln -s fb0pal fb0cl-high
  197. # ln -s fb0multiscan fb0cl-highi
  198. # ln -s fb0multiscan-lace fb0cl-highi+
  199. # ln -s fb0a2024-10 fb0cl-vhigh
  200.  
  201. You should now see this:
  202.  
  203. root@colorpot:/dev> ll fb0cl*
  204. lrwxrwxrwx   1 root        6 Dec 19 15:47 fb0cl-high -> fb0pal
  205. lrwxrwxrwx   1 root       12 Dec 19 15:47 fb0cl-highi -> fb0multiscan
  206. lrwxrwxrwx   1 root       17 Dec 19 15:47 fb0cl-highi+ -> fb0multiscan-lace
  207. lrwxrwxrwx   1 root        7 Dec 19 15:47 fb0cl-low -> fb0ntsc
  208. lrwxrwxrwx   1 root       12 Dec 19 15:47 fb0cl-med -> fb0ntsc-lace
  209. lrwxrwxrwx   1 root       11 Dec 19 15:48 fb0cl-vhigh -> fb0a2024-10
  210.  
  211. Well, that's it. Now you can access the modes through meaningful (or so I
  212. think :-) names, but still have the old Amiga video mode names around.
  213.  
  214. At this time you might wonder what video modes are actually behind those
  215. names; here is a short list:
  216.  
  217. /dev name     resolution    line frequency (kHz)    frame frequency (Hz)
  218.               x     y
  219. fb0cl-low     640   480           31.25                   60
  220. fb0cl-med     800   600           48.1                    72
  221. fb0cl-high    1024  768           56                      70
  222. fb0cl-highi   1024  768           31.3                    77   (*)
  223. fb0cl-highi+  1024  768           46.3                    113  (*)
  224. fb0cl-vhigh   1280  1024          51                      87   (*)
  225.  
  226. (*) interlaced video modes
  227.  
  228. Additionally, you might want to create one more symlink that will be used
  229. for X11 at all times; for instance, I always use the 1024x768 non-interlaced
  230. mode for X11 (which is named "fb0cl-high" in the example above).
  231. So, I create a symlink:
  232.  
  233. # ln -s fb0cl-high fb0x11
  234.  
  235. And now I just tell the Xserver to use this mode when starting:
  236. $ export FRAMEBUFFER=/dev/fb0x11
  237. $ startx
  238.  
  239.  
  240. 5) Installing the utilities
  241. ---------------------------
  242.  
  243. [Please note: Now that it is possible to set the monitor limits immediately
  244. at kernel-startup time, there is no more need for "freq" at all; but I
  245. still include it for your convenience.
  246. For information about setting the monitor limits on the amiboot command line,
  247. see below in "Starting the kernel"].
  248.  
  249. This driver comes with a small tool for maintenance named "freq".
  250. You get both sources and binaries (compiled for libc6 aka glibc).
  251. For now, I suggest to copy the binary to your /sbin directory and having 
  252. your PATH variable point at that location.
  253.  
  254. "freq" allows to inquire or set the current monitor limits for the driver,
  255. on a per-board basis.
  256.  
  257. There used to be another tool named "tog", but this is not required
  258. anymore and will do nothing when started against this driver version;
  259. please delete it. Also, remove any invocations of it, like in your
  260. $HOME/.xinitrc.
  261.  
  262.  
  263. 6) Checking the cabling
  264. -----------------------
  265.  
  266. The cabling for the typical (one-monitor) system is just the same as you
  267. might be used to from AmigaOS: The Amiga's output is connected to the VGA
  268. board's 9-pin input with a short cable, and the VGA board's output is
  269. connected to the monitor. This allows to either see the Amiga video signal
  270. (by letting it pass through the board) or the VGA board's signal (by
  271. switching the toggle). If you start the kernel with "video=clgen", though
  272. (see below, under "Starting the kernel"), the board's own video output is
  273. visible all the time and there is no Amiga display at all, so there is no
  274. need to ever switch back to the Amiga signal.
  275.  
  276. If you have a 2-monitor-setup (one monitor connected to the Amiga, the other
  277. connected to the VGA board), you will see that when you start the kernel
  278. with "video=clgen", the Amiga's signal is just a gray blank screen. This
  279. is so because the Amiga display subsystem is not initialized at all.
  280. You can safely forget about the monitor connected to the Amiga's video
  281. output now.
  282.  
  283. 7) Starting the kernel
  284. ----------------------
  285.  
  286. Starting the kernel with its display on your graphics board works similar to
  287. the way you used to start kernels before: To your list of options passed to 
  288. either amiboot or amiga-lilo (I only use amiboot, so I can't explain what
  289. exactly you have to do to the latter), add the following:
  290.  
  291. video=clgen[:suboption,suboption]
  292.  
  293. The suboptions allow you to set the monitor capabilities or startup video
  294. mode right here, instead of having to use freq or fbset later. Here's
  295. how they have to look like:
  296.  
  297. monitorcap:vmin;vmax;hmin;hmax
  298.  
  299.   where vmin and vmax are vertical minimum and maximum frequencies in Hz,
  300.   and hmin and hmax are horizontal min/max frequencies in kHz(!).
  301.   The default values are "monitorcap:50;90;30;38", which means vertical
  302.   range from 50 to 90 Hz and horizontal range from 30 to 38 kHz.
  303.  
  304. mode:{low|med|high}
  305.   This sets the startup (default) video mode for all consoles.
  306.  
  307.   Name    resolution[pixels]   hfreq[kHz]     vfreq[Hz]   columns  rows
  308.   low        640x480            31.25           60           80     30
  309.   med        800x600            48              72          100     37
  310.   high      1024x768            55.8            70          128     48
  311.  
  312. So, here's as an example a complete line from MY current setup;
  313. don't even think about using exactly this line in your setup:
  314.  
  315.    "video=clgen:monitorcap:50;120;30;86,mode:high"
  316.  
  317. PLEASE NOTE! The ";" character under AmigaOS has the meaning of a comment,
  318. thereby discarding the rest of the line. Therefore, if you use the
  319. "monitorcap:" suboption, don't forget to enclose the whole option in
  320. double quotes (" ") to avoid this misinterpretation of ";". If the kernel
  321. does not start in the way you expected, this is a possible reason; type
  322. "cat /proc/cmdline" to see whether really the whole parameter list was
  323. passed through.
  324.  
  325. When the kernel starts, you should see the clgen driver report its
  326. version number and what hardware it has found, like this:
  327.  
  328. [..]
  329.    0x42000000: Helfrich SD64 Graphics Board (RAM) (Z3, 16M)
  330.    0x00e90000: Helfrich SD64 Graphics Board (REG) (Z2, 64K)
  331.  clgen: Driver for Cirrus Logic based graphic boards, v1.3 (12-Jan-98)
  332.  clgen: Monitor limits set to H: 30000 - 86000 Hz, V: 50 - 120 Hz
  333.  clgen: SD64 board detected;  RAM (16384 KB) at $42000000,  REG at $e90000
  334.  clgen: This board has 4194304 bytes of DRAM memory
  335. [..]
  336.  
  337. Don't be confused by the different numbers for RAM amount (16 MB vs. 4 MB);
  338. the first number is the Zorro address space usage, which is often larger
  339. than the amount of RAM on the board. The number in the last line should
  340. be the actual amount of RAM your board has.
  341.  
  342. At this point you can already open a bottle of champagne, because if you
  343. can read the above messages, it means the driver works for you. The (default)
  344. console looks pretty much like before on OCS/ECS/AGA, but it's now in 
  345. 60 Hz instead of 50 Hz (PAL), and it uses 256 colors. Of course, if you
  346. immediately try to use one of the higher console sizes (mode:med or 
  347. mode:high), it will look even better :-). But for a start it's probably
  348. wise to begin with the default mode and make sure that it works.
  349.  
  350. If you attempt to start the kernel with a video mode that exceeds the
  351. monitor limits, the driver will fall back to the standard "low" mode instead.
  352. Also, if your "monitorcap:" suboption makes no sense, the driver will
  353. switch back to the default of H:30-38 kHz, V:50-90 Hz.
  354.  
  355. The display might be misaligned now (like too wide or not centered).
  356. If your monitor has the ability to store video mode settings (display
  357. size and location), you can use its controls now to center the display.
  358. Though, you can also use fbset to do that; see below, in "Using fbset
  359. to adjust modes".
  360.  
  361.  
  362. 8) Setting/inquiring the monitor limits
  363. ---------------------------------------
  364.  
  365. It is possible that a graphic board can damage the connected monitor by
  366. sending it a video signal with too high or too low line/frame frequencies.
  367. To avoid this, the clgen driver will reject a video mode that would exceed
  368. the specifications of the monitor. But how can the driver know the limits?
  369. The answer is: You have to tell him.
  370.  
  371. By default, clgen assumes that the connected monitor is a "poor" model that
  372. can only do 30 - 38 kHz line frequency and 50 - 90 Hz frame frequency. 
  373. These should be "careful" defaults for most monitors in use nowadays.
  374. Also, the video mode that the board produces at kernel startup is a
  375. very "careful" mode using just 640x480 pixels with 31.5 kHz line frequency
  376. and 60 Hz frame frequency - even fixed-frequency old VGA monitors should
  377. be able to handle this.
  378.  
  379. If you try to activate a mode that exceeds your monitor's limits, you will
  380. get a message from the clgen driver on the current console, like this:
  381.  
  382.       clgen: desired mode exceeds monitor limits (rejected)!
  383.  
  384. If your monitor CAN handle higher frequencies than the default, please look
  385. up its limits in your monitor's manual, and set the corresponding values
  386. in the kernel, using either the "monitorcap:" option as explained in the
  387. previous chapter, or use the "freq" tool to tell the driver about it. 
  388. I recommend using the "monitorcap:" option of amiboot, as your monitor limits
  389. will probably rarely ever change in the near future, and most of the time
  390. there is no need to change the limits during one Linux session.
  391.  
  392. The usage is:
  393.  
  394. Usage: freq [-q] [-f n] [-s minhor:maxhor:minvert:maxvert]
  395.  -q                                queries the current monitor settings
  396.  -f n                              chooses framebuffer driver #n
  397.  -s minhor:maxhor:minvert:maxvert  sets new limits
  398.     All min/max values are in Hertz (hz), e.g. 30000:38000:50:90
  399.  
  400. So, to get the current limits for framebuffer #0 (which is probably
  401. your graphic board), type:
  402.  
  403. root@debian:~> freq -f 0 -q
  404. Current monitor limit settings for fb driver #0 [CLGen:SD64]:
  405. Horizontal: 30000 - 38000 Hz
  406. Vertical: 50 - 90 Hz
  407.  
  408. Let's assume your monitor can do 30 - 58 kHz line frequency, and 50 - 100
  409. Hz frame frequency. Then, you'd type (as root):
  410.  
  411. root@debian:~> freq -f 0 -s 30000:58000:50:100
  412. Monitor limit settings for fb driver #0 [CLGen:SD64] have been set to:
  413. Horizontal: 30000 - 58000 Hz
  414. Vertical: 50 - 100 Hz
  415.  
  416. You see that the limits have been raised, and modes within the new limits
  417. will not be rejected anymore. Please note that modifying the limits is
  418. regarded as a "privileged" operation, and can thus only be executed
  419. by root. Anyone can inquire the current settings, though.
  420.  
  421. PLEASE NOTE: Don't just enter some invented numbers - LOOK UP THE SPECS
  422. IN YOUR MONITOR'S MANUAL! Otherwise you risk damaging your hardware.
  423.  
  424. PLEASE NOTE2: If you are upgrading from the 1.0 driver, check out any place
  425. where you start freq; the framebuffer number is now 0 and not 1 anymore
  426. (as it used to be)!
  427.  
  428. Personal suggestion: If you do not want to use the "monitorcap:" option
  429. for whatever reason, I suggest to put the "freq" invocation into a startup
  430. file like "/etc/init.d/boot" (or however it is called on your installation).
  431. But note that by the time the program is started, your root partition is
  432. probably the only one that is mounted - so keep the "freq" binary in a place
  433. on the root partition (like /sbin).
  434.  
  435. PLEASE NOTE3: Once you have installed the "freq" invocation in a startup
  436. file like suggested in the previous note, starting the kernel with an
  437. Amiga console again ("video=pal-lace" or similar), you might run into
  438. problems when trying to change a mode; this is so because some of the Amiga's
  439. video modes just use 15 kHz line frequency (even if doubled by a hardware
  440. flickerfixer; it's the number that counts), and your monitor can only do 
  441. 30 kHz or above. In that case, you will have to change the monitor limits
  442. again before you can change video modes for it.
  443.  
  444.  
  445. 9) Using fbset to adjust modes
  446. -------------------------------
  447. You have probably 2 choices to center the display on your monitor:
  448. You can either use the monitor itself (newer models are able to store
  449. a lot of video mode settings and immediately activate a stored profile
  450. whenever they recognize a certain frame format), or you use fbset.
  451. fbset also allows to adjust a lot of other things - like, setting totally
  452. new timing parameters. I will not explain the fbset usage in full detail
  453. here; rather, I'll only give a little example of what might be a typical
  454. usage of it for the clgen driver.
  455.  
  456. Let's assume you have sucessfully started the kernel, see the initial
  457. 640x480 image, but it is not centered. Now you can use fbset like this
  458. to move the image around:
  459.  
  460. # fbset -move [left|right|up|down]
  461.  
  462. This will move the image in the corresponding directions (not every
  463. invocation moves the display as the granularity of fbset is finer than
  464. that of the VGA hardware; try invoking it several times to get a feeling
  465. for it).
  466. Similarly, you can set all timing values (-left, -right, -up, -down,
  467. -hslen and -vslen) until you are satisfied. When done, you can ask
  468. fbset to print out the current timing parameters of the "current"
  469. video mode:
  470.  
  471. # fbset -i
  472.  
  473. and write the "mode" part of the output into your /etc/fb.modes file
  474. where it is quickly available. Replace the "name" with a meaningful name
  475. (I suugest to choose a naming scheme that start with "cl-", like "cl-high".
  476. From now on, you can immediately set this mode with a command like
  477. "fbset cl-high".
  478.  
  479. NOTE GPM USERS!
  480. The "gpm" program which lets you do Cut&Paste operations on the console
  481. will not notice when you change the console's video mode (size) and will
  482. continue to use the columns/rows numbers it has determined when it started.
  483. This can lead to two strange things:
  484.  
  485. a) You change to a higher-resolution console: The mouse cursor of gpm will
  486.    not be able to access certain parts of the console (at the far right
  487.    and bottom of the screen).
  488.  
  489. b) You change to a lower-resolution console: It is possible to move the
  490.    mouse cursor out of the visible area.
  491.  
  492. These are no bugs of clgen. My solution suggestions are:
  493. - to fix gpm's signal handling (if it's really the culprit)
  494. - to not change the console size at all (and only use mode:xxx at startup)
  495. - to restart gpm after a console size change
  496.  
  497. In section "Example of fb.modes entries" below you will find a list of
  498. modes that you can append to your /etc/fb.modes file. The listed modes are
  499. exactly the same as those found in the kernel driver (except for the
  500. SuperLoRes mode).
  501.  
  502. All of this still doesn't really help you because the mode used by the kernel
  503. at startup time is not taken from /etc/fb.modes, but from the driver itself;
  504. if you have changed the video mode and want it to appear like that
  505. immediately at kernel startup time, you still have the option to put your
  506. new timings into the driver's mode database itself and compile your own
  507. custom kernel. 
  508.  
  509.  
  510. PLEASE NOTE: THE PARAMETER CHECKING IN THE DRIVER IS VERY INCOMPLETE;
  511. YOU MIGHT BE ABLE TO CREATE A TIMING SETTING THAT CREATES AN UNUSABLE
  512. DISPLAY (WHICH MIGHT EVEN LOCK UP THE COMPUTER). USE FBSET WITH CARE!
  513.  
  514. fbset is also used set an oversized ("autoscroll") display; here is
  515. an example:
  516.  
  517. Let's assume you have a poor monitor that cannot do much better than
  518. 640x480 pixels, which is usually too little for reasonable working in X11.
  519. So, to create a virtual workspace of, say, 1024x768 pixels, you'd
  520. type:
  521. # fbset -ofb /dev/fb0x11 -vxres 1024 -vyres 768
  522.  
  523. Now you just have to tell the Xserver which mode to use, and start it:
  524. # export FRAMEBUFFER=/dev/fb0x11
  525. # startx
  526.  
  527. When the Xserver has started, trying moving the mouse pointer against
  528. the right or bottom border, and you should see the well-known autoscroll
  529. effect.
  530.  
  531.  
  532. 10) Starting/using X11 with clgen
  533. ---------------------------------
  534. The application that's (IMHO) going to be the most-used one is the X
  535. Window System. Unfortunately, using it with the clgen driver is not quite
  536. as easy as is with Linux on i386 machines, but it's very close by now.
  537.  
  538. The only thing you have to do before you can start X is to tell the Xserver
  539. on which framebuffer device it has to work; using bash, this is typically
  540. something like:
  541.  
  542. $ export FRAMEBUFFER=/dev/fb0x11
  543. $ startx
  544.  
  545. Replace the "fb0x11" with whatever video mode device you want to use for X.
  546.  
  547. If you rather start an Xsession via xdm instead of "startx", you will have
  548. to put the "export ..." line into something like /etc/init.d/boot (or 
  549. wherever your xdm gets started). It's just important that FRAMEBUFFER
  550. is set to the correct device name before the Xserver starts.
  551.  
  552.  
  553. 11) Example of fb.modes entries
  554. -------------------------------
  555.  
  556. The following is an excerpt from my /etc/fb.modes file; it provides the
  557. same video modes as those predefined in the clgen driver. Just append this
  558. to your /etc/fb.modes file, and you can immediately switch to one of them
  559. by feeding its name (from the "mode" line) to fbset, like so:
  560.  
  561. $ fbset cl-med
  562.  
  563. This will of course only work if:
  564.  - your monitor can operate at the desired frequency
  565.  - you set the monitor limits with freq accordingly
  566.  
  567.  
  568. ########################
  569. ## CLGen modes, as found in the predefined modes in the driver
  570. ########################
  571.  
  572. # 640x480. This mode should work on ANY Multiscan monitor
  573. mode "cl-low"
  574.     # H: 31.250 kHz, V: 59.524 Hz
  575.     geometry 640 480 640 480 8
  576.     timings 40000 32 32 33 10 96 2
  577.     hsync high
  578.     vsync high
  579.     bcast false
  580. endmode
  581.  
  582. # 800x600. Nices for consoles
  583. mode "cl-med"
  584.     # H: 48.077 kHz, V: 72.188 Hz
  585.     geometry 800 600 800 600 8
  586.     timings 20000 64 56 23 37 120 6
  587.     hsync high
  588.     vsync high
  589.     bcast false
  590. endmode
  591.  
  592. # 1024x768, non-interlaced. If your monitor can do this, it's a
  593. # good choice for X11.
  594. mode "cl-high"
  595.     # H: 55.866 kHz, V: 69.399 Hz
  596.     geometry 1024 768 1024 768 8
  597.     timings 12500 92 112 31 2 204 4
  598.     hsync high
  599.     vsync high
  600.     bcast false
  601. endmode
  602.  
  603. # 1024x768, interlaced. If your monitor is not capable of high
  604. # horizontal frequencies, this might be a good alternative to cl-high.
  605. mode "cl-highi"
  606.     # H: 31.360 kHz, V: 76.769 Hz
  607.     geometry 1024 768 1024 768 8
  608.     timings 22268 92 112 32 9 204 8
  609.     hsync high
  610.     vsync high
  611.     laced true
  612.     bcast false
  613. endmode
  614.  
  615. # 1024x768 interlaced, but with a bit higher frequencies, so less flicker.
  616. mode "cl-highi+"
  617.     # H: 46.240 kHz, V: 113.196 Hz
  618.     geometry 1024 768 1024 768 8
  619.     timings 15102 92 112 32 9 204 8
  620.     hsync high
  621.     vsync high
  622.     laced true
  623.     bcast false
  624. endmode
  625.  
  626. # 1280x1024 interlaced. For those who want "full-size" X11. :-)
  627. mode "cl-vhigh"
  628.     # H: 51.020 kHz, V: 87.589 Hz
  629.     geometry 1280 1024 1280 1024 8
  630.     timings 12500 56 16 128 1 216 12
  631.     hsync high
  632.     vsync high
  633.     laced true
  634.     bcast false
  635. endmode
  636.  
  637.  
  638.  
  639. 12) Not-Yet-Features(tm), ToDo's
  640. --------------------------------
  641.  
  642. - A copy of the driver's mode database should be created for each board
  643.   detected. This is not yet done. Currently all initialized boards share
  644.   the same video mode database in the driver.
  645.  
  646. - Activate 15/24/32 bit modes once the Xserver at least supports some of
  647.   them (24/32 bits should not be too hard, but 16 bits is almost impossible
  648.   because the upper/lower bytes are swapped on the bus (on some of the
  649.   boards at least), so that you cannot access the colors as in 
  650.   "rrrrrggg gggbbbbb", but instead "gggbbbbb rrrrrggg" which the Xserver
  651.   will probably never be able to cope with).
  652.  
  653. - Make use of the BitBlt engine for X11: I understand that lacking blitter 
  654.   support leaves a good deal of the hardware capabilities unused, but the 
  655.   current framebuffer driver does not make any provisions for using 
  656.   accelerated hardware in an application program (like the Xserver).
  657.   Probably once we adopt the ggi concept, this might be added.
  658.   Until then, there is nothing I can do about it. But at least the console
  659.   is already accelerated.
  660.  
  661.  
  662. 13) Non-features(tm), also known as Known bugs
  663. ----------------------------------------------
  664.  
  665. - In 320x200 DoubleScan mode, a one pixel wide column is visible at the left
  666.   border that should actually be at the right border. I haven't yet found
  667.   the reason for this.
  668.  
  669. - A few safety checks are still not in there. Use the driver, but don't stress
  670.   it to its limits :-}.
  671.  
  672.  
  673. 14) Credits
  674. -----------
  675.  
  676. There are a couple of persons I'd like to thank: 
  677. - Uli Sigmund of Viona, Karlsruhe, for providing me with Cluster sources
  678.   of his EGS drivers.
  679. - Joerg Ringelberg of Viona, Karlsruhe, for supplying me with the databooks
  680.   for CL GD542x/5434.
  681. - Klaus Burkert of Villagetronic for some hints on Fifo threshold settings
  682.   during the Steinhagen Amiga meeting in October '96, and also for info
  683.   on how to turn off the VideoCapture unit on the P4.
  684. - My professor of the Computer Graphics department, Peter Gorny, for
  685.   accepting this as topic for a "Studienarbeit". I always knew studying
  686.   CAN be fun at times. :-)
  687. - Jes Soerensen for maintaining the Linux m68k kernel source since 1.3.xx
  688.   so well (also thanks for this nice little parcel that made my ZipRAM farm
  689.   complete :-)
  690. - Martin Apel; his Cybervision driver for Linux is not really a very complete
  691.   driver (yet? ;-), but due to its simplicity it helped understand some
  692.   of the ideas behind fb.
  693. - Geert Uytterhoeven for several helpful hints and suggestions
  694. - Anyone else involved in making Linux/m68k as usable and stable as it is
  695.   now. Although I believe we won't be able to push Billyboy Gates out
  696.   of the market with this, it shows how well people from all over the world
  697.   can cooperate in the Internet to work on a common goal.
  698. - All you users who bugged me then and now about when this beast will be
  699.   released; I know it took MUCH longer than I had expected/told you,
  700.   but after all it's out now, and is free. Forgive me.
  701. - The "beta guinea pigs" :-) on IRC - Chels, Nes, pCp, you know who you are.
  702.   Thanks for testing&bug reporting.
  703.  
  704.  
  705. 15) Contacting the author
  706. ------------------------
  707.  
  708. If you 
  709.  - find a bug in the CLGen driver
  710.  - want to tell me how good/bad it works in your environment
  711.  - have source patches/suggestions
  712.  
  713. please contact me via E-Mail: Frank.Neumann@Informatik.Uni-Oldenburg.DE
  714. Especially if you found something that should be added to this documentation
  715. file, I'll gladly accept it.
  716. I do get LOTS of mail every day, so bear with me if replying takes a while.
  717. (these "lots" do not come from thousands and millions of clgen users, but
  718. from those too much mailing lists I'm subscribed to ;-). Oh, and one more
  719. thing: I DO NOT LIKE MIME-MAIL.
  720.  
  721. The newest version of this driver should always be available through my
  722. homepage: http://www.informatik.uni-oldenburg.de/~amigo/
  723. Look out for some "Linux/m68k" stuff in that page. I'm sure you'll be
  724. able to find it! :-)
  725.  
  726. If you want to report a bug, please don't forget to include:
  727.  - what kernel you are running
  728.  - what version of clgen you are using
  729.  - what system configuration you have
  730.  - how you triggered the bug
  731.  - whether the problem is reproducible or not
  732.  - ..and any other information that might be helpful.
  733.  
  734.  
  735. 16) History
  736. ----------
  737.  
  738.  *  - 16-Mar-1997: v1.0 First public release
  739.  *  - 22-Oct-1997: v1.1 Added basic console support, P4 support (not working)
  740.  *                      This was never released to the public
  741.  *  - 19-Dec-1997: v1.2 Public release
  742.  *                      working console support
  743.  *                      working P4 support
  744.  *                      hardware-accelerated RectFill/BitBLT on consoles
  745.  *                      (only in 8 bits right now)
  746.  *                      correct standard VGA colour table
  747.  *                      1 bit support working again
  748.  *                      uses the FB_ACTIVATE_* flags correctly now
  749.  *                      correct behaviour when used with fbset
  750.  * - 12-Jan-1998: v1.3  Public release
  751.  *                      correct CLUT handling for Picasso4 (was BGR, not RGB)
  752.  *                      removed left-over printk for Picasso II
  753.  *                      now accepts monitorcap: and mode: on command line
  754.  *                      correct "scrolling" when height or width = 0
  755.  *                      (though that's been done in console/fbcon.c)
  756.  
  757.  
  758. 42) Final words
  759. ---------------
  760.  
  761. Well, good luck now, and of course: You use this driver at your own risk.
  762. If it blows your computer, monitor, cat or girl-friend, I'm not responsible
  763. for that. If it causes a parallel universe to be opened, I'll be interested
  764. in hearing how you managed to do that, though. :-)
  765. This is free software, but I'd never reject signs of appreciation. Even
  766. a little postcard is something I'd always welcome.
  767. Personal plug: I might be able to finish my studies sometime in spring '99 - 
  768. got an interesting job then? Here I am. :-)
  769.  
  770. Frank, 12 Jan 1998
  771. --
  772. +        Frank Neumann, Hauptstr. 107, 26131 Oldenburg, Germany         +
  773. +     InterNet: Frank.Neumann@informatik.uni-oldenburg.de IRC:Franky    +